<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- This file documents the use of the GNU compilers.

Copyright © 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<title>PowerPC AltiVec Built-in Functions Available on ISA 3.0 (Using the GNU Compiler Collection (GCC))</title>

<meta name="description" content="PowerPC AltiVec Built-in Functions Available on ISA 3.0 (Using the GNU Compiler Collection (GCC))">
<meta name="keywords" content="PowerPC AltiVec Built-in Functions Available on ISA 3.0 (Using the GNU Compiler Collection (GCC))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Indices.html" rel="index" title="Indices">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="PowerPC-AltiVec_002fVSX-Built_002din-Functions.html" rel="up" title="PowerPC AltiVec/VSX Built-in Functions">
<link href="PowerPC-AltiVec-Built_002din-Functions-Available-on-ISA-3_002e1.html" rel="next" title="PowerPC AltiVec Built-in Functions Available on ISA 3.1">
<link href="PowerPC-AltiVec-Built_002din-Functions-Available-on-ISA-2_002e07.html" rel="prev" title="PowerPC AltiVec Built-in Functions Available on ISA 2.07">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
kbd.key {font-style: normal}
span:hover a.copiable-link {visibility: visible}
-->
</style>


</head>

<body lang="en_US">
<div class="subsubsection-level-extent" id="PowerPC-AltiVec-Built_002din-Functions-Available-on-ISA-3_002e0">
<div class="nav-panel">
<p>
Next: <a href="PowerPC-AltiVec-Built_002din-Functions-Available-on-ISA-3_002e1.html" accesskey="n" rel="next">PowerPC AltiVec Built-in Functions Available on ISA 3.1</a>, Previous: <a href="PowerPC-AltiVec-Built_002din-Functions-Available-on-ISA-2_002e07.html" accesskey="p" rel="prev">PowerPC AltiVec Built-in Functions Available on ISA 2.07</a>, Up: <a href="PowerPC-AltiVec_002fVSX-Built_002din-Functions.html" accesskey="u" rel="up">PowerPC AltiVec/VSX Built-in Functions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsubsection" id="PowerPC-AltiVec-Built_002din-Functions-Available-on-ISA-3_002e0-1"><span>6.60.23.4 PowerPC AltiVec Built-in Functions Available on ISA 3.0<a class="copiable-link" href="#PowerPC-AltiVec-Built_002din-Functions-Available-on-ISA-3_002e0-1"> &para;</a></span></h4>

<p>The following additional built-in functions are also available for the
PowerPC family of processors, starting with ISA 3.0
(<samp class="option">-mcpu=power9</samp>) or later.
</p>
<p>Only instructions excluded from the PVIPR are listed here.
</p>
<div class="example smallexample">
<pre class="example-preformatted">unsigned int scalar_extract_exp (double source);
unsigned long long int scalar_extract_exp (__ieee128 source);

unsigned long long int scalar_extract_sig (double source);
unsigned __int128 scalar_extract_sig (__ieee128 source);

double scalar_insert_exp (unsigned long long int significand,
                          unsigned long long int exponent);
double scalar_insert_exp (double significand, unsigned long long int exponent);

ieee_128 scalar_insert_exp (unsigned __int128 significand,
                            unsigned long long int exponent);
ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent);

int scalar_cmp_exp_gt (double arg1, double arg2);
int scalar_cmp_exp_lt (double arg1, double arg2);
int scalar_cmp_exp_eq (double arg1, double arg2);
int scalar_cmp_exp_unordered (double arg1, double arg2);

bool scalar_test_data_class (float source, const int condition);
bool scalar_test_data_class (double source, const int condition);
bool scalar_test_data_class (__ieee128 source, const int condition);

bool scalar_test_neg (float source);
bool scalar_test_neg (double source);
bool scalar_test_neg (__ieee128 source);
</pre></div>

<p>The <code class="code">scalar_extract_exp</code> and <code class="code">scalar_extract_sig</code>
functions require a 64-bit environment supporting ISA 3.0 or later.
The <code class="code">scalar_extract_exp</code> and <code class="code">scalar_extract_sig</code> built-in
functions return the significand and the biased exponent value
respectively of their <code class="code">source</code> arguments.
When supplied with a 64-bit <code class="code">source</code> argument, the
result returned by <code class="code">scalar_extract_sig</code> has
the <code class="code">0x0010000000000000</code> bit set if the
function&rsquo;s <code class="code">source</code> argument is in normalized form.
Otherwise, this bit is set to 0.
When supplied with a 128-bit <code class="code">source</code> argument, the
<code class="code">0x00010000000000000000000000000000</code> bit of the result is
treated similarly.
Note that the sign of the significand is not represented in the result
returned from the <code class="code">scalar_extract_sig</code> function.  Use the
<code class="code">scalar_test_neg</code> function to test the sign of its <code class="code">double</code>
argument.
</p>
<p>The <code class="code">scalar_insert_exp</code>
functions require a 64-bit environment supporting ISA 3.0 or later.
When supplied with a 64-bit first argument, the
<code class="code">scalar_insert_exp</code> built-in function returns a double-precision
floating point value that is constructed by assembling the values of its
<code class="code">significand</code> and <code class="code">exponent</code> arguments.  The sign of the
result is copied from the most significant bit of the
<code class="code">significand</code> argument.  The significand and exponent components
of the result are composed of the least significant 11 bits of the
<code class="code">exponent</code> argument and the least significant 52 bits of the
<code class="code">significand</code> argument respectively.
</p>
<p>When supplied with a 128-bit first argument, the
<code class="code">scalar_insert_exp</code> built-in function returns a quad-precision
ieee floating point value.  The sign bit of the result is copied from
the most significant bit of the <code class="code">significand</code> argument.
The significand and exponent components of the result are composed of
the least significant 15 bits of the <code class="code">exponent</code> argument and the
least significant 112 bits of the <code class="code">significand</code> argument respectively.
</p>
<p>The <code class="code">scalar_cmp_exp_gt</code>, <code class="code">scalar_cmp_exp_lt</code>,
<code class="code">scalar_cmp_exp_eq</code>, and <code class="code">scalar_cmp_exp_unordered</code> built-in
functions return a non-zero value if <code class="code">arg1</code> is greater than, less
than, equal to, or not comparable to <code class="code">arg2</code> respectively.  The
arguments are not comparable if one or the other equals NaN (not a
number). 
</p>
<p>The <code class="code">scalar_test_data_class</code> built-in function returns 1
if any of the condition tests enabled by the value of the
<code class="code">condition</code> variable are true, and 0 otherwise.  The
<code class="code">condition</code> argument must be a compile-time constant integer with
value not exceeding 127.  The
<code class="code">condition</code> argument is encoded as a bitmask with each bit
enabling the testing of a different condition, as characterized by the
following:
</p><div class="example smallexample">
<pre class="example-preformatted">0x40    Test for NaN
0x20    Test for +Infinity
0x10    Test for -Infinity
0x08    Test for +Zero
0x04    Test for -Zero
0x02    Test for +Denormal
0x01    Test for -Denormal
</pre></div>

<p>The <code class="code">scalar_test_neg</code> built-in function returns 1 if its
<code class="code">source</code> argument holds a negative value, 0 otherwise.
</p>
<p>The following built-in functions are also available for the PowerPC family
of processors, starting with ISA 3.0 or later
(<samp class="option">-mcpu=power9</samp>).  These string functions are described
separately in order to group the descriptions closer to the function
prototypes.
</p>
<p>Only functions excluded from the PVIPR are listed here.
</p>
<div class="example smallexample">
<pre class="example-preformatted">int vec_all_nez (vector signed char, vector signed char);
int vec_all_nez (vector unsigned char, vector unsigned char);
int vec_all_nez (vector signed short, vector signed short);
int vec_all_nez (vector unsigned short, vector unsigned short);
int vec_all_nez (vector signed int, vector signed int);
int vec_all_nez (vector unsigned int, vector unsigned int);

int vec_any_eqz (vector signed char, vector signed char);
int vec_any_eqz (vector unsigned char, vector unsigned char);
int vec_any_eqz (vector signed short, vector signed short);
int vec_any_eqz (vector unsigned short, vector unsigned short);
int vec_any_eqz (vector signed int, vector signed int);
int vec_any_eqz (vector unsigned int, vector unsigned int);

signed char vec_xlx (unsigned int index, vector signed char data);
unsigned char vec_xlx (unsigned int index, vector unsigned char data);
signed short vec_xlx (unsigned int index, vector signed short data);
unsigned short vec_xlx (unsigned int index, vector unsigned short data);
signed int vec_xlx (unsigned int index, vector signed int data);
unsigned int vec_xlx (unsigned int index, vector unsigned int data);
float vec_xlx (unsigned int index, vector float data);

signed char vec_xrx (unsigned int index, vector signed char data);
unsigned char vec_xrx (unsigned int index, vector unsigned char data);
signed short vec_xrx (unsigned int index, vector signed short data);
unsigned short vec_xrx (unsigned int index, vector unsigned short data);
signed int vec_xrx (unsigned int index, vector signed int data);
unsigned int vec_xrx (unsigned int index, vector unsigned int data);
float vec_xrx (unsigned int index, vector float data);
</pre></div>

<p>The <code class="code">vec_all_nez</code>, <code class="code">vec_any_eqz</code>, and <code class="code">vec_cmpnez</code>
perform pairwise comparisons between the elements at the same
positions within their two vector arguments.
The <code class="code">vec_all_nez</code> function returns a
non-zero value if and only if all pairwise comparisons are not
equal and no element of either vector argument contains a zero.
The <code class="code">vec_any_eqz</code> function returns a
non-zero value if and only if at least one pairwise comparison is equal
or if at least one element of either vector argument contains a zero.
The <code class="code">vec_cmpnez</code> function returns a vector of the same type as
its two arguments, within which each element consists of all ones to
denote that either the corresponding elements of the incoming arguments are
not equal or that at least one of the corresponding elements contains
zero.  Otherwise, the element of the returned vector contains all zeros.
</p>
<p>The <code class="code">vec_xlx</code> and <code class="code">vec_xrx</code> functions extract the single
element selected by the <code class="code">index</code> argument from the vector
represented by the <code class="code">data</code> argument.  The <code class="code">index</code> argument
always specifies a byte offset, regardless of the size of the vector
element.  With <code class="code">vec_xlx</code>, <code class="code">index</code> is the offset of the first
byte of the element to be extracted.  With <code class="code">vec_xrx</code>, <code class="code">index</code>
represents the last byte of the element to be extracted, measured
from the right end of the vector.  In other words, the last byte of
the element to be extracted is found at position <code class="code">(15 - index)</code>.
There is no requirement that <code class="code">index</code> be a multiple of the vector
element size.  However, if the size of the vector element added to
<code class="code">index</code> is greater than 15, the content of the returned value is
undefined.
</p>
<p>The following functions are also available if the ISA 3.0 instruction
set additions (<samp class="option">-mcpu=power9</samp>) are available.
</p>
<p>Only functions excluded from the PVIPR are listed here.
</p>
<div class="example smallexample">
<pre class="example-preformatted">vector long long vec_vctz (vector long long);
vector unsigned long long vec_vctz (vector unsigned long long);
vector int vec_vctz (vector int);
vector unsigned int vec_vctz (vector int);
vector short vec_vctz (vector short);
vector unsigned short vec_vctz (vector unsigned short);
vector signed char vec_vctz (vector signed char);
vector unsigned char vec_vctz (vector unsigned char);

vector signed char vec_vctzb (vector signed char);
vector unsigned char vec_vctzb (vector unsigned char);

vector long long vec_vctzd (vector long long);
vector unsigned long long vec_vctzd (vector unsigned long long);

vector short vec_vctzh (vector short);
vector unsigned short vec_vctzh (vector unsigned short);

vector int vec_vctzw (vector int);
vector unsigned int vec_vctzw (vector int);

vector int vec_vprtyb (vector int);
vector unsigned int vec_vprtyb (vector unsigned int);
vector long long vec_vprtyb (vector long long);
vector unsigned long long vec_vprtyb (vector unsigned long long);

vector int vec_vprtybw (vector int);
vector unsigned int vec_vprtybw (vector unsigned int);

vector long long vec_vprtybd (vector long long);
vector unsigned long long vec_vprtybd (vector unsigned long long);
</pre></div>

<p>On 64-bit targets, if the ISA 3.0 additions (<samp class="option">-mcpu=power9</samp>)
are available:
</p>
<div class="example smallexample">
<pre class="example-preformatted">vector long vec_vprtyb (vector long);
vector unsigned long vec_vprtyb (vector unsigned long);
vector __int128 vec_vprtyb (vector __int128);
vector __uint128 vec_vprtyb (vector __uint128);

vector long vec_vprtybd (vector long);
vector unsigned long vec_vprtybd (vector unsigned long);

vector __int128 vec_vprtybq (vector __int128);
vector __uint128 vec_vprtybd (vector __uint128);
</pre></div>

<p>The following built-in functions are available for the PowerPC family
of processors, starting with ISA 3.0 or later (<samp class="option">-mcpu=power9</samp>).
</p>
<p>Only functions excluded from the PVIPR are listed here.
</p>
<div class="example smallexample">
<pre class="example-preformatted">__vector unsigned char
vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2);
__vector unsigned short
vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2);
__vector unsigned int
vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2);
</pre></div>

<p>The <code class="code">vec_absd</code>, <code class="code">vec_absdb</code>, <code class="code">vec_absdh</code>, and
<code class="code">vec_absdw</code> built-in functions each computes the absolute
differences of the pairs of vector elements supplied in its two vector
arguments, placing the absolute differences into the corresponding
elements of the vector result.
</p>
<p>The following built-in functions are available for the PowerPC family
of processors, starting with ISA 3.0 or later (<samp class="option">-mcpu=power9</samp>):
</p><div class="example smallexample">
<pre class="example-preformatted">vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int);
vector unsigned long long vec_vrlnm (vector unsigned long long,
                                     vector unsigned long long);
</pre></div>

<p>The result of <code class="code">vec_vrlnm</code> is obtained by rotating each element
of the first argument vector left and ANDing it with a mask.  The
second argument vector contains the mask  beginning in bits 11:15,
the mask end in bits 19:23, and the shift count in bits 27:31,
of each element.
</p>
<p>If the cryptographic instructions are enabled (<samp class="option">-mcrypto</samp> or
<samp class="option">-mcpu=power8</samp>), the following builtins are enabled.
</p>
<p>Only functions excluded from the PVIPR are listed here.
</p>
<div class="example smallexample">
<pre class="example-preformatted">vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);

vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
                                                    vector unsigned long long);

vector unsigned long long __builtin_crypto_vcipherlast
                                     (vector unsigned long long,
                                      vector unsigned long long);

vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
                                                     vector unsigned long long);

vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long,
                                                         vector unsigned long long);

vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
                                                vector unsigned char,
                                                vector unsigned char);

vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
                                                 vector unsigned short,
                                                 vector unsigned short);

vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
                                               vector unsigned int,
                                               vector unsigned int);

vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
                                                     vector unsigned long long,
                                                     vector unsigned long long);

vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
                                               vector unsigned char);

vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short,
                                                vector unsigned short);

vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int,
                                              vector unsigned int);

vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long,
                                                    vector unsigned long long);

vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long,
                                                       int, int);

vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int);
</pre></div>

<p>The second argument to <var class="var">__builtin_crypto_vshasigmad</var> and
<var class="var">__builtin_crypto_vshasigmaw</var> must be a constant
integer that is 0 or 1.  The third argument to these built-in functions
must be a constant integer in the range of 0 to 15.
</p>
<p>The following sign extension builtins are provided:
</p>
<div class="example smallexample">
<pre class="example-preformatted">vector signed int vec_signexti (vector signed char a);
vector signed long long vec_signextll (vector signed char a);
vector signed int vec_signexti (vector signed short a);
vector signed long long vec_signextll (vector signed short a);
vector signed long long vec_signextll (vector signed int a);
vector signed long long vec_signextq (vector signed long long a);
</pre></div>

<p>Each element of the result is produced by sign-extending the element of the
input vector that would fall in the least significant portion of the result
element. For example, a sign-extension of a vector signed char to a vector
signed long long will sign extend the rightmost byte of each doubleword.
</p>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="PowerPC-AltiVec-Built_002din-Functions-Available-on-ISA-3_002e1.html">PowerPC AltiVec Built-in Functions Available on ISA 3.1</a>, Previous: <a href="PowerPC-AltiVec-Built_002din-Functions-Available-on-ISA-2_002e07.html">PowerPC AltiVec Built-in Functions Available on ISA 2.07</a>, Up: <a href="PowerPC-AltiVec_002fVSX-Built_002din-Functions.html">PowerPC AltiVec/VSX Built-in Functions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
